Chapter 3
Installation

Joachim Reichel and Fernando Cacciola

Table of Contents

3.1 Introduction
3.2 Supported Compilers
3.3 CMake
3.4 Third Party Software
   3.4.1   Standard Template Library
   3.4.2   Boost
   3.4.3   GMP and MPFR
   3.4.4   CORE
   3.4.5   Leda
   3.4.6   RS
   3.4.7   OpenNL
   3.4.8   Eigen
   3.4.9   Taucs
   3.4.10   Blas
   3.4.11   Lapack
   3.4.12   Qt
   3.4.13   libQGLViewer
   3.4.14   Coin
   3.4.15   zlib
   3.4.16   ESTBL
3.5 Downloading Cgal
3.6 Configuring Cgal
   3.6.1   Configuring Cgal with the CMake Gui
   3.6.2   Configuring Cgal with the cmake command-line tool
   3.6.3   Cgal Libraries
   3.6.4   Examples and Demos
   3.6.5   Debug vs. Release
   3.6.6   Static vs. Shared Libraries
   3.6.7   Multiple Variants of makefiles
3.7 Building Cgal Libraries
3.8 Installing Cgal Libraries
3.9 Configuring and Building Programs Using Cgal
   3.9.1   Custom flags in the programs using Cgal
   3.9.2   Creating a cmake script for a program using Cgal
3.10 Summary of Configuration Variables
   3.10.1   Component selection
   3.10.2   Compiler and Linker Flags
   3.10.3   Miscellaneous Variables
   3.10.4   Variables providing information about 3rd-party libraries
3.11 Example
3.12 Compiler Workarounds
3.13 Compiler Optimizations
3.14 Scripts
   3.14.1   cgal_create_cmake_script

3.1   Introduction

This document describes how to install Cgal on Windows, Unix-like systems, and MacOS X.

Ideally, installing Cgal amounts to:

  cd  CGAL-4.0.1                                # go to CGAL directory
  cmake .                                     # configure CGAL
  make                                        # build the CGAL libraries
  cd examples/Straight_skeleton_2             # go to an example directory
  cmake -DCGAL_DIR=$HOME/CGAL-4.0.1 .           # configure the examples
  make                                        # build the examples 

In a less ideal world, you probably have to install CMake, a makefile generator, and third party libraries. That's what this manual is about.

3.2   Supported Compilers

In order to build the Cgal libraries, you need a C++ compiler. Cgal 4.0.1is supported for the following compilers/operating systems:

compiler operating system
Gnu g++ 3.4 or later 1 Linux / MacOS X
MS Windows 95/98/2000/XP/NT4
Intel C++ 11.0 or later2 Linux
MS Visual C++ 9.0, 10.0 (Visual Studio 2008 and 2010)3 MS Windows 95/98/2000/XP/NT4/Vista/7

3.3   CMake

In order to configure, build, and install the Cgal libraries, examples and demos, you need CMake, a cross-platform ``makefile generator''. If CMake is not installed already you can obtain it from http://www.cmake.org/. CMake version 2.6.2 or higher is required. On Windows, CMake version 2.8.6 or higher is required, for a proper support of DLLs generation.

3.4   Third Party Software

The focus of Cgal is at geometry, and we rely on other highly specialized libraries and software for non-geometric issues, e.g., numeric solvers or visualization.

Note that there is no need to first install all the software listed below. Only the STL and Boost are required by all Cgal packages.

3.4.1   Standard Template Library

Cgal heavily uses the STL, and in particular adopted many of its design ideas. You can find online documentation for the STL at various web sites, e.g., http://www.sgi.com/tech/stl/, http://www.cplusplus.com/reference/, or http://msdn.microsoft.com/en-us/library/1fe2x6kt(VS.100).aspx.

The STL comes with the compiler, so there is nothing to install.

3.4.2   Boost

The Boost libraries are a set of portable C++ source libraries. Most of Boost libraries are header-only, but a few of them need to be compiled or installed as binaries.

Cgal requires the Boost libraries. In particular the header files and the threading library (Boost.Thread binaries. Version 1.39 (or higher) are needed.

On Windows, as auto-linking is used, you also need the binaries of Boost.Serialization and Boost.DateTime, but the dependency is artificial and used only at link-time: the CGAL libraries do not depend on the DLLs of those two libraries.

In Cgal some demos also depend on Boost.Program_options.

In case the Boost libraries are not installed on your system already, you can obtain them from http://www.boost.org/. For Windows you can download an installer from http://www.boostpro.com/download/. Since Boost.Thread is required, make sure to either install the precompiled libraries for your compiler or build libboost-thread.

As on Windows there is no canonical directory for where to find Boost, we recommend that you define the environment variable BOOST_ROOT and set it to where you have installed Boost, e.g., C:\boost\boost_1_41_0.

3.4.3   GMP and MPFR

Gmp and Mpfr are libraries for multi precision integers and rational numbers, and for multi precision floating point numbers.

Cgal combines floating point arithmetic with exact arithmetic, in order to be efficient and reliable. Cgal has a built-in number type for that, but Gmp and Mpfr provide a faster solution, and we recommend to use them.

Having Gmp version 4.2 or higher and Mpfr version 2.2.1 or higher installed is recommended. These libraries can be obtained from http://gmplib.org/ and http://www.mpfr.org/, respectively.

As Visual C++ is not properly supported by the Gmp and Mpfr projects, we provide precompiled versions of Gmp and Mpfr, which can be downloaded with the installer CGAL-4.0.1-Setup.exe.

3.4.4   CORE

Core is a library that provides a number type for computing with real numbers; that is, it allows to represent expressions with square roots involved. This package is useful when dealing with curved objects.

Core is needed by the Cgal kernel that deals with algebraic numbers.

Core can be downloaded from http://www.cs.nyu.edu/exact/', but we recommend to use the version of Core that is distributed with Cgal.

3.4.5   Leda

Leda is a library of efficient data structures and algorithms. Like Core, Leda offers a real number data type.

In Cgal this library is optional, and its number types can be used as an alternative to Gmp, Mpfr, and Core.

Free and commercial editions of Leda are available from http://www.algorithmic-solutions.com/leda/index.html.

3.4.6   RS

RS (Real Solutions) is devoted to the study of the real roots of polynomial systems with a finite number of complex roots (including univariate polynomials).

In Cgal RS is used by one model of the Algebraic Kernel.

RS is freely distributable for non-commercial use. You can download it from http://vegas.loria.fr/rs/. The library RS needs Mpfi, which can be downloaded from http://mpfi.gforge.inria.fr/. Version 1.4 or higher is recommended.

3.4.7   OpenNL

OpenNL (Open Numerical Library) is a library used to easily construct and solve sparse linear systems.

In Cgal it is the default solver for the Surface Mesh Parameterization package.

The OpenNL's main Web page is http://alice.loria.fr/index.php/software/4-library/23-opennl.html. Cgal includes a version of OpenNL in C++ made especially for Cgal by Bruno Lévy.

3.4.8   Eigen

Eigen is a C++ template library for linear algebra. Eigen supports all matrix sizes, various matrix decomposition methods and sparse linear solvers.

In Cgal, Eigen provides sparse linear solvers in the Surface Reconstruction from Point Sets and the Planar Parameterization of Triangulated Surface Meshes packages. Since Cgal version 4.0, Eigen is recommended over Taucs that is not longer maintained.

In addition, Eigen also provides singular value decomposition for the Estimation of Local Differential Properties and the Approximation of Ridges and Umbilics packages.

The usage of Eigen allows to remove lapack, blas and Taucs from the list of third party libraries required by some Cgal packages. Note that the version 3.1 (or greater) of Eigen is required.

The Eigen web site is http://eigen.tuxfamily.org.

3.4.9   Taucs

Taucs is a library of sparse linear solvers.

In Cgal, Taucs can be used by the Surface Reconstruction from Point Sets package, and by the Planar Parameterization of Triangulated Surface Meshes package. Note that since Cgal 4.0, Eigen is recommended over Taucs.

The Taucs website is http://www.tau.ac.il/~stoledo/taucs/.
The latest official version is Taucs version 2.2, September 4, 2003. Copyright (c) 2001, 2002, 2003 by Sivan Toledo, Tel-Aviv University, stoledo@tau.ac.il. All Rights Reserved.
See http://www.tau.ac.il/~stoledo/taucs/ for the license and the availability note.
Used by permission of Sivan Toledo.

The Cgal project provides a modified version of Taucs in the download section of http://www.cgal.org/. This version fixes some bugs, supports 64-bit platforms, and allows a simplified installation process. It also contains a complete lapack implementation.

As Visual C++ is not properly supported by the Taucs project, we provide a precompiled version of Taucs, which can be downloaded with the installer CGAL-4.0.1-Setup.exe.

CAUTION: Since version 3.3.1, Cgal is no longer compatible with the official release of Taucs (currently 2.2). Make sure to use the modified version provided in the download section.

3.4.10   Blas

blas (Basic Linear Algebra Subprograms) is a library of basic vector and matrix operations.

In Cgal, blas can be used by the packages Estimation of Local Differential Properties and Approximation of Ridges and Umbilics only. Note that if Eigen is available on the system, blas is not required anymore.

You can download the official release from http://www.netlib.org/blas/. Alternatively, installing Taucs customized for Cgal provides blas.

3.4.11   Lapack

lapack provides routines for solving systems of simultaneous linear equations, least-squares solutions of linear systems of equations, eigenvalue problems, and singular value problems.

In Cgal, lapack can be used by the packages Estimation of Local Differential Properties and Approximation of Ridges and Umbilics only. Note that if Eigen is available on the system, lapack is not required anymore.

You can download the official release from http://www.netlib.org/lapack/. Alternatively, installing Taucs customized for Cgal provides lapack.

3.4.12   Qt

Qt is a cross-platform application and UI framework.

Most Cgal demos use Qt3 or Qt4. Having Qt4 version 4.3.0 or higher is recommended.

In case Qt is not yet installed on your system, you can download it from http://qt.nokia.com/.

3.4.13   libQGLViewer

libQGLViewer is a 3D widget based on Qt 4's QGLWidget.

In Cgal some 3D demos are based on libQGLViewer.

It can be downloaded from http://www.libqglviewer.com/.

3.4.14   Coin

Coin is an implementation of Open Inventor.

In Cgal, Coin is used in the demo of the Kinetic Data Structures package.

You can download it from http://www.coin3d.org/.

3.4.15   zlib

zlib is a data compression library.

In Cgal this library is used in the examples of the Surface Mesh Generation package.

If it is not already on your system, e.g., on Windows, you can download it from http://www.zlib.net/.

3.4.16   ESTBL

The Esbtl (Easy Structural Biology Template Library) is a library that allows the handling of Pdb data.

In Cgal the Esbtl is used in an example of the 3D Skin Surface Meshing package.

It can be downloaded from http://esbtl.sourceforge.net/.

3.5   Downloading Cgal

The Cgal library can be downloaded from http://www.cgal.org/download.html.

After you have downloaded the file CGAL-4.0.1.tar.gz containing the Cgal sources, you have to unpack it. Under a Unix-like shell, use the command:

      tar xzf CGAL-4.0.1.tar.gz

When you are on Windows you may download and run CGAL-4.0.1-Setup.exe. It is a self extracting executable that installs the Cgal source, and that allows you to select and download some precompiled third party libraries.

In both cases the directory CGAL-4.0.1 will be created. This directory contains the following subdirectories:

directory contents
auxiliary precompiled GMP, MPFR and TAUCS for Windows
config configuration files for install script
cmake/modules modules for finding and using libraries
demo demo programs (most of them need Qt, geomview or other third-party products)
doc_html documentation (HTML)
doc_pdf documentation (PDF)
examples example programs
include header files
scripts some useful scripts (e.g. for creating CMakeLists.txt files)
src source files

The directories include/CGAL/CORE and src/CGALCore contain a distribution of the Core library4 version 1.7 for dealing with algebraic numbers. Core is not part of Cgal and has its own license.

The only documentation shipped with Cgal sources is the present installation manual. The Cgal manual must be downloaded separately from http://www.cgal.org/download.html.

The directory include/CGAL/OpenNL contains a distribution of the Open Numerical Library which provides solvers for sparse linear systems, especially designed for the Computer Graphics community. OpenNL is not part of Cgal and has its own license.

3.6   Configuring Cgal

Before building Cgal you have to choose the compiler/linker, set compiler and linker flags, specify which third-party libraries you want to use and where they can be found, and which Cgal libraries you want to build. Gathering all this information is called configuration.

The configuration uses CMake, a cross-platform build system generator that can generate makefiles, or IDE project files. This manual explains only those features of CMake which are needed in order to build Cgal. Please refer to the CMake documentation at http://www.cmake.org/ for further details.

The CMake configuration process generates a makefile or a Visual C++ solution and project file that you can use to build Cgal.

3.6.1   Configuring Cgal with the CMake Gui

The simplest way to start the configuration is to run the graphical user interface of CMake. We recommend to use cmake-gui. It is available on all platforms since CMake version 2.6. You must pass as argument the root directory of Cgal. For example:

  cd  CGAL-4.0.1
  cmake-gui . # Notice the dot to indicate the current directory.

Once cmake-gui has started up, you must press 'Configure'. A dialog will pop up and you will have to choose what shall get generated. After you have made your choice and pressed 'ok', you will see the output of configuration tests in the lower window of the application. When these tests are done, you will see many red entries in the upper window. Just ignore them and press once again 'Configure'. By now CMake should have found many libraries and have initialized variables. If you still find red entries you have to provide the necessary information. This typically happens if you have installed software at non-standard locations. Providing information and pressing 'Configure' goes on until all entries are grayed. You are now ready to press 'Generate'. Once this is done, you can quit cmake-gui.

3.6.2   Configuring Cgal with the cmake command-line tool

Alternatively, you can run the command-line tool called cmake. You pass as argument the root directory of Cgal. For example:

  cd  CGAL-4.0.1
  cmake . # Notice the dot to indicate the current directory.

The very first thing CMake does is to detect the compiler to use. This detection is performed by a special CMake module called a generator. A CMake generator understands the build requirements for a particular compiler/linker and generates the necessary files for that. For example, the UNIX Makefiles generator understands the GNU toolchain (g++, gcc, ld etc.) and produces makefiles, which can be used to build a target by a simple call to make. Likewise, the Visual Studio 2005 generator produces solution and project files and can be manually launched in the VS IDE to build the target.

Each platform has a default generator, so you only need to select one when the default is not what you want. For example, under Windows, it is possible to generate NMakefiles instead of Visual Studio project files in order to build the library with nmake. Running cmake with no parameters in a command-line prints the list of available generators supported by your platform and CMake version. If the generator you need is not listed there, you can try a newer CMake version, as generators are hardcoded into CMake, and additional generators are added with each release.

Since the choice of the generator determines the type of build files to generate, in some cases you choose a particular generator as a mean to choose a specific compiler (because they use different build files). For example, the following generates solution files for use in Visual C++ 9.0:

  cd CGAL-4.0.1
  cmake -G"Visual Studio 9 2008" . 

In other cases, however, the generator doesn't directly identify a specific compiler but a tool chain. For example, the UNIX Makefiles generator produces makefiles that call some auto-detected command-line compiler, like gcc. If you need the makefiles to use a different compiler, you need to specify the desired compiler in the call to CMake, as in this example:

  cd CGAL-4.0.1
  cmake -DCMAKE_CXX_COMPILER:FILEPATH=g++-3.4 . 

CMake maintains configuration parameters in so-called cmake variables, like the CMAKE_CXX_COMPILER in the example above. These variables are not environment variables but CMake variables. Some of the CMake variables represent user choices, such as WITH_examples or CMAKE_BUILD_TYPE=Release, while others indicate the details of a third-party library, such as Boost_INCLUDE_DIR or the compiler flags to use, such as CMAKE_CXX_FLAGS.

The command line tool cmake accepts CMake variables as arguments of the form -D<VAR>:<TYPE>=<VALUE>, as in the example above, but this is only useful if you already know which variables need to be explicitly defined.

CMake keeps the variables that a user can manipulate in a so-called CMake cache, a simple text file named CMakeCache.txt, whose entries are of the form VARIABLE:TYPE=VALUE. Advanced users can manually edit this file, instead of going through the interactive configuration session.

The configuration process not only determines the location of the required dependencies, it also dynamically generates a compiler_config.h file, which encodes the properties of your system and a special file named CGALConfig.cmake, which is used to build programs using Cgal. The purpose of this file is explained below.

3.6.3   Cgal Libraries

Cgal is split into six libraries. During configuration, you can select the libraries that you would like to build by setting a CMake variable of the form WITH_<library>. By default all are switched ON.

library CMake variable functionality dependencies
CGAL none Main library GMP, MPFR, Boost (headers)
and Boost.Thread (library)
CGAL_Core WITH_CGAL_Core The CORE library for algebraic numbers.15 GMP and MPFR
CGAL_Qt3 WITH_CGAL_Qt3 CGAL::Qt_widget used by Qt3-based demos Qt3 and OpenGL
CGAL_Qt4 WITH_CGAL_Qt4 QGraphicsView support for Qt4-based demos Qt4 and OpenGL
CGAL_ImageIO WITH_CGAL_ImageIO Utilities to read and write image files OpenGL, ZLib, VTK (optional)

If you turn off the configuration of a library, you can still configure it manually from the source directory:

  cd CGAL-4.0.1/src/CGALQt4 
  cmake . # configures only the CGAL_Qt4 library

3.6.4   Examples and Demos

Cgal is distributed with a large collection of examples and demos. By default, these are NOT configured along with the Cgal libraries, unless you set the variables WITH_examples=ON and/or WITH_demos=ON.

Nevertheless, even when configured with Cgal, they are not automatically built along with the libraries. You must build the examples or demos make targets (or IDE projects) explicitly.

3.6.5   Debug vs. Release

The CMake variable CMAKE_BUILD_TYPE to indicate how to build the libraries. It accepts the values Release or Debug. The default depends on the platform, so it is recommended that you always indicate the build type explicitly. For performance reasons, you should always use Release, unless you want to debug your program.

This is not an issue for solution/project files, as there the user selects the build type from within the IDE.

3.6.6   Static vs. Shared Libraries

Shared libraries, also called dynamic-link libraries, are built by default (.dll on Windows, .so on Linux, .dylib on MacOS). You can choose to produce static libraries instead by setting the CMake variable BUILD_SHARED_LIBS to FALSE. If you use cmake-gui, that variable appears as a checkable option in the graphical user interface.

3.6.7   Multiple Variants of makefiles

While you can choose between release or debug builds, and shared or static libraries, it is not possible to generate different variants during a single configuration. You need to run CMake in a different directory for each variant you are interested in, each with its own selection of configuration parameters.

CMake stores the resulting makefiles and project files, along with several temporary and auxiliary files such as the variables cache, in the directory where it is executed, called CMAKE_BINARY_DIR, but it takes the source files and configuration scripts from CMAKE_SOURCE_DIR.

The binary and source directories do not need to be the same. Thus, you can configure multiple variants by creating a distinct directory for each configuration and by running CMake from there. This is known in CMake terminology as out-of-source configuration, as opposite to an in-source configuration, as showed in the previous sections.

You can, for example, generate subdirectories CGAL-4.0.1/cmake/platforms/debug and CGAL-4.0.1/cmake/platforms/release for two configurations, respectively:

mkdir CGAL-4.0.1/cmake/platforms/debug
cd CGAL-4.0.1/cmake/platforms/debug
cmake -DCMAKE_BUILD_TYPE=Debug ../../..

mkdir CGAL-4.0.1/cmake/platforms/release
cd CGAL-4.0.1/cmake/platforms/release
cmake -DCMAKE_BUILD_TYPE=Release ../../..

3.7   Building Cgal Libraries

The results of a successful configuration are build file that control the build step. The nature of the build files depends on the generator used during configuration, but in all cases they contain several targets, one per library, and a default global target corresponding to all the libraries.

For example, in a UNIX-like environment the default generator produces makefiles. You can use the make command-line tool for the succeeding build step as follows:


cd CGAL-4.0.1

# build all the selected libraries at once

make 


# build just the libraries needed for the Surface mesher demo

make  CGAL  CGAL_ImageIO CGAL_Qt4

The resulting are placed in the subdirectory lib under <CMAKE_BINARY_DIR> (which is CGAL-4.0.1 in case you run an in-source-configuration).

With generators other than UNIX Makefiles the resulting build files are solution and project files which should be launched in an Ide, such as Visual Studio or KDevelop3. They will contain the targets described above, which you can manually build as with any other solution/project within your Ide.

Alternatively, you can build it with the command line version of the Visual Studio Ide:


    devenv CGAL.sln /Build Debug

The "Debug" argument is needed because CMake creates solution files for all four configurations, and you need to explicitly choose one when building (the other choices are Release, RelWithDebInfo and MinSizeRel).

The build files produced by CMake are autoconfigured. That is, if you change any of the dependencies, the build step automatically goes all the way back to the configuration step. This way, once the target has been configured the very first time by invoking cmake, you don't necessarily need to invoke cmake again. Rebuilding will call itself cmake and re-generate the build file whenever needed. Keep this in mind if you configure Cgal for the Visual Studio IDE since a build could then change the solution/project file in-place and VS will prompt you to reload it.

If you have turned on the configuration of examples and/or demos, there will be additional targets named examples and demos, plus one target for each example and each demo in the build files. None of these targets are included by default, so you need to build them explicitly after the Cgal libraries have been successfully built. The targets examples and demos include themselves all the targets for examples and demos respectively.


# build all examples at once
make examples 

# build all demos at once
make demos

# build only the Straight Skeleton demo
make Straight_skeleton_2_demo

When using UNIX Makefiles you can find out the exact name of the example or demo target of a particular package by typing make help | grep <package>.

3.8   Installing Cgal Libraries

On many platforms, library pieces such as headers, docs and binaries are expected to be placed in specific locations. A typical example being /usr/include and /usr/lib on Unix-like operating systems or C:/Program Files/ on Windows. The process of placing or copying the library elements into its standard location is sometimes referred to as Installation and it is a postprocessing step after the build step.

CMake carries out the installation by producing a build target named install. The following example shows a typical session from configuration to installation in a Unix-like environment:


cd CGAL-4.0.1

cmake .      # configure
make         # compile
make install # install

If you use a generator that produces IDE files (for Visual Studio for instance) there will be an optional INSTALL project, which you will be able to ``build'' to execute the installation step.

The files are copied into a directory tree relative to the installation directory determined by the CMake variable CMAKE_INSTALL_PREFIX. This variable defaults to /usr/local under UNIX-like operating systems and C:\Program Files under Windows. If you want to install to a different location, you must override that CMake variable explicitly at the configuration time and not when executing the install step.

The file CGALConfig.cmake is installed by default in $CMAKE_INSTALLED_PREFIX/lib/CGAL-4.0.1.

3.9   Configuring and Building Programs Using Cgal

CMake can be used to configure and build user programs as well via a CMake script (CMakeLists.txt). All the examples and demos contain such CMake scripts.

During configuration of the Cgal libraries a file named CGALConfig.cmake is generated in the binary directory. This file contains the definitions of several CMake variable that summarize the configuration of Cgal. In order to configure a user program, you need to indicate the location of that config file in the CMake variable CGAL_DIR:


cd CGAL-4.0.1/examples/Straight_skeleton_2
cmake -DCGAL_DIR=$HOME/CGAL-4.0.1 .
make

CGAL_DIR can also be an environment variable.

If you have installed CGAL, CGAL_DIR must afterward be set to $CMAKE_INSTALLED_PREFIX/lib/CGAL.

3.9.1   Custom flags in the programs using Cgal

Normally, programs linked with Cgal must be compiled with the same flags used by the compilation of Cgal libraries. For this reason, the very first time a program is configured, all the flags given by the CMake variables CMAKE_*_FLAGS are locked in the sense that the values recorded in CGALConfig.cmake are used to override any values given by CMake itself or yourself.

This does not apply to the additional flags that can be given via CGAL_*_FLAGS.

Such inherited values are then recorded in the current CMake cache for the program. The flags are then unlocked in the sense that at any subsequent configuration you can provide your own flags and this time they will not be overridden.

When using the interactive cmake-gui the first press on Configure unlocks the flags, so that you can edit them as needed.

The locking of flags is controlled by the variable CGAL_DONT_OVERRIDE_CMAKE_FLAGS which starts out FALSE and is toggled right after the flags have been loaded from CGALConfig.cmake.

If you use the command line tool you can specify flags directly by setting the controlling variable right up front:


cd CGAL-4.0.1

cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS=-g .

cd CGAL-4.0.1/examples/Straight_skeleton_2

cmake -DCGAL_DIR=CGAL-4.0.1 -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_FLAGS=-O2 -DCGAL_DONT_OVERRIDE_CMAKE_FLAGS=TRUE . 

3.9.2   Creating a cmake script for a program using Cgal

For relatively simple programs the Bourne-shell script cgal_create_cmake_script can be used (a short description of this file is provided in Appendix 3.14.1). More generally, within a cmake script, once Cgal has been found using find_package the variable CGAL_USE_FILE is set to a compilation environment CMake file. Including this file within a cmake script sets up include paths and libraries to link with of Cgal and third party libraries.

3.10   Summary of Configuration Variables

Most configuration variables are not environment variables but CMake variables. They are given in the command line to CMake via the -D option, or passed from the interactive interface of cmake-gui. Unless indicated differently, all the variables summarized below are CMake variables.

3.10.1   Component selection

The following boolean variables indicate which Cgal components to configure and build. Their values can be ON or OFF.

Variable Default value
WITH_examples OFF
WITH_demos OFF
WITH_CGAL_Core ON
WITH_CGAL_Qt3 ON
WITH_CGAL_Qt4 ON
WITH_CGAL_ImageIO ON

3.10.2   Compiler and Linker Flags

The following variables specify compiler and linker flags. Each variable holds a space-separated list of command-line switches for the compiler and linker and their default values are automatically defined by CMake based on the target platform.

Have in mind that these variables specify a list of flags, not just one single flag. If you provide your own definition for a variable, you will entirely override the list of flags chosen by CMake for that particular variable.

The variables that correspond to both debug and release builds are always used in conjunction with those for the specific build type.

Program Both Debug and Release Release only Debug Only
C++ Compiler CMAKE_CXX_FLAGS CMAKE_CXX_FLAGS_RELEASE CMAKE_CXX_FLAGS_DEBUG
Linker (shared libs) CMAKE_SHARED_LINKER_FLAGS CMAKE_SHARED_LINKER_FLAGS_RELEASE CMAKE_SHARED_LINKER_FLAGS_DEBUG
Linker (static libs) CMAKE_MODULE_LINKER_FLAGS CMAKE_MODULE_LINKER_FLAGS_RELEASE CMAKE_MODULE_LINKER_FLAGS_DEBUG
Linker (programs) CMAKE_EXE_LINKER_FLAGS CMAKE_EXE_LINKER_FLAGS_RELEASE CMAKE_EXE_LINKER_FLAGS_DEBUG

Additional Compiler and Linker Flags

The following variables can be used to add flags without overriding the ones defined by cmake.

Program Both Debug and Release Release only Debug Only
C++ Compiler CGAL_CXX_FLAGS CGAL_CXX_FLAGS_RELEASE CGAL_CXX_FLAGS_DEBUG
Linker (shared libs) CGAL_SHARED_LINKER_FLAGS CGAL_SHARED_LINKER_FLAGS_RELEASE CGAL_SHARED_LINKER_FLAGS_DEBUG
Linker (static libs) CGAL_MODULE_LINKER_FLAGS CGAL_MODULE_LINKER_FLAGS_RELEASE CGAL_MODULE_LINKER_FLAGS_DEBUG
Linker (programs) CGAL_EXE_LINKER_FLAGS CGAL_EXE_LINKER_FLAGS_RELEASE CGAL_EXE_LINKER_FLAGS_DEBUG

3.10.3   Miscellaneous Variables

Variable Description Type Default value
CMAKE_BUILD_TYPE Indicates type of build. Possible values are 'Debug' or 'Release' CMake Release
CMAKE_CXX_COMPILER Full-path to the executable corresponding to the C++ compiler to use. CMake platform-dependent
CXX Idem Environment Idem

Variables used only when building programs (such as demos or examples)

Variable Description Type Default value
CGAL_DIR Full-path to the binary directory where Cgal was configured Either CMake or Environment none

3.10.4   Variables providing information about 3rd-party libraries

The following variables provide information about the availability and location of the 3rd party libraries used by Cgal. CMake automatically searches for dependencies so you need to specify these variables if CMake was unable to locate something. This is indicated by a value ending in NOTFOUND.

Since 3rd-party libraries are system wide, many of the CMake variables listed below can alternatively be given as similarly-named environment variables instead. Keep in mind that you must provide one or the other but never both.

Boost libraries

In most cases, if boost is not automatically found, setting the BOOST_ROOT variable is enough. If it is not, you can specify the header and library directories individually. You can also provide the full pathname to a specific compiled library if it cannot be found in the library directory or its name is non-standard.

By default, when Boost binary libraries are needed, the shared versions of them are used, if present. You can set the variable CGAL_Boost_USE_STATIC_LIBS to ON if you want to link with static versions explicitly.

On Windows, if you link with Boost shared libraries, you must ensure that the .dll files are found by the dynamic linker, at run time. You can, for example, add the path to the Boost .dll to the PATH environment variable.

Variable Description Type
BOOST_ROOT16 Root directory of your boost installation Either CMake or Environment
Boost_INCLUDE_DIR Directory containing the boost/version.hpp file CMake
BOOST_INCLUDEDIR Idem Environment
Boost_LIBRARY_DIRS Directory containing the compiled boost libraries CMake
BOOST_LIBRARYDIR Idem Environment
Boost_(xyz)_LIBRARY_RELEASE Full pathname to a release build of the compiled 'xyz' boost library CMake
Boost_(xyz)_LIBRARY_DEBUG Full pathname to a debug build of the compiled 'xyz' boost library CMake
CGAL_Boost_USE_STATIC_LIBS Link with static Boost libraries (Boolean) CMake

GMP and MPFR libraries

Under Windows, auto-linking is used, so only the directory containing the libraries is needed and you would specify GMP|MPFR_LIBRARY_DIR rather than GMP|MPFR_LIBRARIES. On the other hand, under Linux the actual library filename is needed. Thus you would specify GMP|MPFR_LIBRARIES. In no case you need to specify both.

Cgal uses both gmp and mpfr, so both need to be supported. If either of them is unavailable the usage of gmp and of mpfr will be disabled.

Variable Description Type
WITH_GMP Indicates whether to search and use gmp/mpfr or not CMake
GMP_INCLUDE_DIR Directory containing the gmp.h file CMake
GMP_INC_DIR Idem Environment
GMP_LIBRARIES_DIR Directory containing the compiled gmp library CMake
GMP_LIB_DIR Idem Environment
GMP_LIBRARIES Full pathname of the compiled gmp library CMake
MPFR_INCLUDE_DIR Directory containing the mpfr.h file CMake
MPFR_INC_DIR Idem Environment
MPFR_LIBRARIES_DIR Directory containing the compiled mpfr library CMake
MPFR_LIB_DIR Idem Environment
MPFR_LIBRARIES Full pathname of the compiled mpfr library CMake

Under Linux, the GMPXX is also searched for, and you may specify the following variables:

Variable Description Type
GMPXX_INCLUDE_DIR Directory containing the gmpxx.h file CMake
GMPXX_LIBRARIES Full pathname of the compiled gmpxx library CMake

MPFI library

Cgal provides a number type based on this library, but the Cgal library itself does not depend on MPFI. This means that this library must be configured when compiling an application that uses the above number type.

When MPFI files are not on the standard path, the locations of the headers and library files must be specified by using environment variables.

Variable Description Type
MPFI_INCLUDE_DIR Directory containing the mpfi.h file CMake
MPFI_INC_DIR Idem Environment
MPFI_LIBRARIES_DIR Directory containing the compiled mpfi library CMake
MPFI_LIB_DIR Idem Environment
MPFI_LIBRARIES Full pathname of the compiled mpfi library CMake

LEDA library

When the LEDA libraries are not automatically found, yet they are installed on the system with base names 'leda' and 'ledaD' (for the release and debug versions resp.), it might be sufficient to just indicate the library directory via the LEDA_LIBRARY_DIRS variable. If that doesn't work because, for example, the names are different, you can provide the full pathnames of each variant via LEDA_LIBRARY_RELEASE and LEDA_LIBRARY_DEBUG.

The variables specifying definitions and flags can be left undefined if they are not needed by LEDA.

Variable Description Type
WITH_LEDA Indicates whether to search and use LEDA or not CMake
LEDA_INCLUDE_DIR Directory containing the file LEDA/system/basic.h CMake
LEDA_LIBRARIES Directory containing the compiled LEDA libraries CMake
LEDA_INC_DIR Directory containing the file LEDA/system/basic.h Environment
LEDA_LIB_DIR Directory containing the compiled LEDA libraries Environment
LEDA_LIBRARY_RELEASE Full pathname to a release build of the LEDA library Either CMake
LEDA_LIBRARY_DEBUG Full pathname to a debug build of the LEDA library Either CMake
LEDA_DEFINITIONS Preprocessor definitions Either CMake
LEDA_CXX_FLAGS Compiler flags Either CMake
LEDA_LINKER_FLAGS Linker flags Either CMake

Qt3 library

In most cases, if Qt3 is not automatically found, setting the QTDIR environment variable is sufficient. If it is not, you can specify the directory containing the header files and the full pathnames of the Qt3 libraries.

Variable Description Type
QTDIR Root directory of the Qt3 library Environment
QT3_INCLUDE_DIR Directory containing the qt.h file CMake
QT3_QT_LIBRARY Full pathname to the qt library of Qt3 CMake
QT3_QTMAIN_LIBRARY Full pathname to the qtmain library of Qt3 CMake
QT3_QASSISTANTCLIENT_LIBRARY Full pathname to the qassistantclient library of Qt3 CMake
QT3_MOC_EXECUTABLE Full pathname to the moc executable of Qt3 CMake
QT3_UIC_EXECUTABLE Full pathname to the uic executable of Qt3 CMake

Qt4 library

The CMake scripts that search for Qt4 can use the introspection feature of the tool qmake included in Qt4 distributions. If Qt4 is not automatically found, it is sufficient to set the PATH environment variable, so that Qt4 qmake tool is in the path, and before Qt3 qmake if that one exists. One can alternatively set the CMake variable QT_QMAKE_EXECUTABLE. The following variables should be then assigned automatically by CMake.

Variable Description Type
QT_INCLUDE_DIR Directory containing the QtCore/qglobal.h file CMake
QT_LIBRARY_DIR Directory containing the compiled Qt4 libraries CMake
QT_(xyz)_LIBRARY Full pathname to the compiled 'xyz' Qt4 library17 CMake
QT_QMAKE_EXECUTABLE Full pathname to the qmake executable of Qt4 CMake
QT_MOC_EXECUTABLE Full pathname to the moc executable of Qt4 CMake
QT_UIC_EXECUTABLE Full pathname to the uic executable of Qt4 CMake

QGLViewer library

Some demos require the GLViewer library.

In most cases, if QGLViewer is not automatically found, setting the QGLVIEWERROOT environment variable is sufficient. If it is not, you can specify the directory containing the header files and the full pathnames of the release and debug libraries

Variable Description Type
QGLVIEWERROOT Root directory of the QGViewer library Environment
QGLVIEWER_INCLUDE_DIR Directory containing the QGLViewer/qglviewer.h file CMake
QGLVIEWER_LIBRARY_RELEASE Full pathname to a release build of the QGLViewer library CMake
QGLVIEWER_LIBRARY_DEBUG Full pathname to a debug build of the QGLViewer library CMake

Eigen library

Eigen is a header-only template library. Only the directory containing the header files of Eigen 3.1 (or greater) is needed.

Variable Description Type
EIGEN3_INCLUDE_DIR Directory containing the file signature_of_eigen3_matrix_library CMake
EIGEN3_INC_DIR Idem Environment

TAUCS and METIS libraries

Some demos require the TAUCS and METIS libraries. If any of the two is not found, the TAUCS support is disabled.

Under Windows, auto-linking is used, so only the directory containing the libraries is needed, and you would specify TAUCS_LIBRARY_DIR rather than TAUCS_LIBRARIES. On the other hand, under Linux the actual library filename is needed. Thus you would specify TAUCS_LIBRARIES. In no case you need to specify both.

Cgal uses both TAUCS and METIS so both need to be supported. If either of them is unavailable the usage of TAUCS-METIS will be disabled.

Variable Description Type
TAUCS_INCLUDE_DIR Directory containing the taucs.h file CMake
TAUCS_INC_DIR Idem Environment
TAUCS_LIBRARIES_DIR Directory containing the compiled taucs library CMake
TAUCS_LIB_DIR Idem Environment
TAUCS_LIBRARY Full pathname of the compiled taucs library CMake
METIS_LIBRARY Full pathname of the compiled metis library CMake

BLAS and LAPACK libraries

A few demos require some BLAS and LAPACK functions. There are several implementations by different vendors that contains the required functions, and CMake searches for most of them.

If they are not found, you can indicate the directory containing the libraries, or provide a semi-colon separated list of pathnames to the libraries which collectively implement the functions.

Many of the libraries implementing BLAS and LAPACK require the F2C library for Fortran-to-C convertion. If this is needed and not found, you may specify the fullpath of the library in the F2C_LIBRARIES variable. You do not need to provide this, if the BLAS|LAPACK libraries do not need f2c.

Variable Description Type
BLAS_INCLUDE_DIR Directory containing blas header files CMake
BLAS_LIBRARIES_DIR Directory containing the compiled libraries implementing BLAS Environment
BLAS_LIB_DIR Idem Environment
BLAS_LIBRARIES Semi-colon separated list of library pathnames implementing the BLAS functions CMake
BLAS_LINKER_FLAGS Linker flags CMake
BLAS_DEFINITIONS Preprocessor definitions CMake
LAPACK_INCLUDE_DIR Directory containing blas header files CMake
LAPACK_LIBRARIES_DIR Directory containing the compiled libraries implementing LAPACK Environment
LAPACK_LIB_DIR Idem Environment
LAPACK_LIBRARIES Semi-colon separated list of library pathnames implementing the LAPACK functions CMake
LAPACK_LINKER_FLAGS Linker flags CMake
LAPACK_DEFINITIONS Preprocessor definitions CMake
F2C_LIBRARIES Full pathname to the f2c library CMake

RS library

As said before, only the Cgal univariate algebraic kernel depends on the library RS. As the algebraic kernel is not compiled as a part of the Cgal library, this library is not detected nor configured at installation time.

CMake will try to find RS in the standard header and library directories. When it is not automatically detected, the locations of the headers and library files must be specified using environment variables.

RS needs Gmp 4.2 or later and Mpfi 1.3.4 or later. The variables related to the latter library may also need to be defined.

Variable Description Type
RS_INCLUDE_DIR Directory containing the rs_exports.h file CMake
RS_INC_DIR Idem Environment
RS_LIBRARIES_DIR Directory containing the compiled rs library CMake
RS_LIB_DIR Idem Environment
RS_LIBRARIES Full pathname of the compiled rs library CMake

ESBTL library

One skin surface example requires the ESBTL library in order to read PDB files.

If ESBTL is not automatically found, setting the ESBTL_INC_DIR environment variable is sufficient.

Variable Description Type
ESBTL_INC_DIR Directory containing the ESBTL/default.h file Environment
ESBTL_INCLUDE_DIR Directory containing the ESBTL/default.h file CMake

3.11   Example

Below is an example output on a Windows machine with VC8 installed, using CMake 2.6, and the following command-line call to cmake:

cmake -DWITH_examples=false 
      -DWITH_demos=false 
      -DCMAKE_BUILD_TYPE=Release 
      ../../..

-- Check for working C compiler: cl
-- Check for working C compiler: cl -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working CXX compiler: cl
-- Check for working CXX compiler: cl -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- CGAL_REFERENCE_CACHE_DIR=
-- Building static libraries
-- Targetting Visual Studio 8 2005
-- Target build environment supports auto-linking
-- Using VC80 compiler.
-- Build type: Release
-- Generator uses intermediate configuration directory: $(OutDir)
-- CMake version: 2.6.1
-- System: Windows
-- CGAL_MAJOR_VERSION=3
-- CGAL_MINOR_VERSION=4
-- CGAL_BUILD_VERSION=442
-- CGAL_SONAME_VERSION=3
-- CGAL_SOVERSION     =3.0.0
-- Boost version: 1.35.0
-- Found the following Boost libraries:
--   thread
-- Boost include:      C:/Program Files/boost/boost_1_35_0
-- Boost libraries:    
-- Boost definitions:  
-- USING BOOST_VERSION = '1.35.0'
-- Could NOT find GMP
-- Could NOT find MPFR
-- Performing Test CGAL_CFG_DENORMALS_COMPILE_BUG - Success
-- Performing Test CGAL_CFG_IEEE_754_BUG - Success
-- Performing Test CGAL_CFG_ISTREAM_INT_BUG - Success
-- Performing Test CGAL_CFG_LONGNAME_BUG - Failed
-- Performing Test CGAL_CFG_MATCHING_BUG_5 - Success
-- Performing Test CGAL_CFG_MATCHING_BUG_6 - Failed
-- Performing Test CGAL_CFG_NESTED_CLASS_FRIEND_DECLARATION_BUG - Failed
-- Performing Test CGAL_CFG_NET2003_MATCHING_BUG - Failed
-- Performing Test CGAL_CFG_NO_CPP0X_ARRAY - Failed
-- Performing Test CGAL_CFG_NO_CPP0X_DECLTYPE - Failed
-- Performing Test CGAL_CFG_NO_CPP0X_DEFAULT_TEMPLATE_ARGUMENTS_FOR_FUNCTION_TEMPLATES - Failed
-- Performing Test CGAL_CFG_NO_CPP0X_DELEGATING_CONSTRUCTORS - Failed
-- Performing Test CGAL_CFG_NO_CPP0X_ISFINITE - Failed
-- Performing Test CGAL_CFG_NO_CPP0X_LONG_LONG - Success
-- Performing Test CGAL_CFG_NO_CPP0X_RVALUE_REFERENCE - Failed
-- Performing Test CGAL_CFG_NO_CPP0X_VARIADIC_TEMPLATES - Failed
-- Performing Test CGAL_CFG_NO_LIMITS - Success
-- Performing Test CGAL_CFG_NO_NEXTAFTER - Failed
-- Performing Test CGAL_CFG_NO_STATEMENT_EXPRESSIONS - Failed
-- Performing Test CGAL_CFG_NO_STL - Success
-- Performing Test CGAL_CFG_NO_TMPL_IN_TMPL_PARAM - Success
-- Performing Test CGAL_CFG_NO_TR1_ARRAY - Failed
-- Performing Test CGAL_CFG_NUMERIC_LIMITS_BUG - Success
-- Performing Test CGAL_CFG_OUTOFLINE_MEMBER_DEFINITION_BUG - Success
-- Performing Test CGAL_CFG_TYPENAME_BEFORE_DEFAULT_ARGUMENT_BUG - Failed
-- Performing Test CGAL_CFG_USING_BASE_MEMBER_BUG_2 - Success
-- CMAKE_INSTALL_PREFIX=C:/Program Files/CGAL
-- USING CUSTOM_CXXFLAGS = ' -D_CRT_SECURE_NO_DEPRECATE -D_SCL_SECURE_NO_DEPRECATE -D_CRT_SECURE_NO_WARNINGS -D_SCL_SECURE_NO_WARNINGS   -D_SECURE_SCL=0'
-- USING        CXXFLAGS = ' /DWIN32 /D_WINDOWS /W3 /Zm1000 /EHsc /GR /MD /O2 /Ob2 /D NDEBUG'
-- USING CUSTOM_LDFLAGS = '  '
-- USING        LDFLAGS = ' '
-- USING CUSTOM_EXEFLAGS = '  '
-- USING        EXEFLAGS = ' /MANIFEST /STACK:10000000 /machine:I386 /INCREMENTAL:NO'
-- Configuring CGALCore. Set WITH_CGALCore to FALSE to unselect it.
-- CGAL-core++ needs GMP and MPFR, cannot be configured.
-- Configuring CGALimageIO. Set WITH_CGALimageIO to FALSE to unselect it.
-- Could NOT find ZLIB
-- CGAL-ImageIO needs ZLib and OpenGL, cannot be configured.
-- Configuring CGALQt. Set WITH_CGALQt to FALSE to unselect it.
-- CGAL-Qt3 needs Qt3, cannot be configured.
-- Configuring CGALQt4. Set WITH_CGALQt4 to FALSE to unselect it.
-- Looking for Q_WS_X11
-- Looking for Q_WS_X11 - not found.
-- Looking for Q_WS_WIN
-- Looking for Q_WS_WIN - found
-- Looking for Q_WS_QWS
-- Looking for Q_WS_QWS - not found.
-- Looking for Q_WS_MAC
-- Looking for Q_WS_MAC - not found.
-- OpenGL include:     
-- OpenGL libraries:   glu32;opengl32
-- OpenGL definitions: 
-- Qt4 include:        C:/Work/Downloaded/Libraries/qt-win-opensource-src-4.4.1/include
-- Qt4 libraries:      optimized;C:/Work/Downloaded/Libraries/qt-win-opensource-src-4.4.1/lib/qtmain.lib;debug;C:/Work/Downloaded/Libraries/qt-win-opensource-src-4.4.1/lib/qtmaind.lib;optimized;C:/Work/Downloaded/Libraries/qt-win-opensource-src-4.4.1/lib/QtOpenGL4.lib;debug;C:/Work/Downloaded/Libraries/qt-win-opensource-src-4.4.1/lib/QtOpenGLd4.lib;opengl32.lib glu32.lib gdi32.lib user32.lib;optimized;C:/Work/Downloaded/Libraries/qt-win-opensource-src-4.4.1/lib/QtGui4.lib;debug;C:/Work/Downloaded/Libraries/qt-win-opensource-src-4.4.1/lib/QtGuid4.lib;imm32;winmm;optimized;C:/Work/Downloaded/Libraries/qt-win-opensource-src-4.4.1/lib/QtCore4.lib;debug;C:/Work/Downloaded/Libraries/qt-win-opensource-src-4.4.1/lib/QtCored4.lib;ws2_32
-- Qt4 definitions:    -DQT_DLL
-- moc executable:     C:/Work/Downloaded/Libraries/qt-win-opensource-src-4.4.1/bin/moc.exe
-- uic executable:     C:/Work/Downloaded/Libraries/qt-win-opensource-src-4.4.1/bin/uic.exe
-- Configuring done
-- Generating done
-- Build files have been written to: C:/Work/Active/GeometryFactory/CGAL/Autotest/CGAL-4.0.1/cmake/platforms/a

3.12   Compiler Workarounds

A number of boolean flags are used to workaround compiler bugs and limitations. They all start with the prefix CGAL_CFG. These flags are used to work around compiler bugs and limitations. For example, the flag CGAL_CFG_NO_CPP0X_LONG_LONG denotes that the compiler does not know the type long long.

For each compiler a file <CGAL/compiler_config.h> is defined, with the correct settings of all flags. This file is generated automatically by CMake, and it is located in the include directory of where you run CMake. For an in-source configuration this means CGAL-3.x/include.

The test programs used to generate the compiler_config.h file can be found in config/testfiles. Both compiler_config.h and the test programs contain a short description of the problem. In case of trouble with one of the CGAL_CFG flags, it is a good idea to take a look at it.

The file CGAL/compiler_config.h is included from <CGAL/config.h>. which is included by all Cgal header files.

3.13   Compiler Optimizations

By default CMake generates makefiles for Release mode, with optimization flags switched on, and vcproj files for Release and Debug modes.

3.14   Scripts

3.14.1   cgal_create_cmake_script

The Bourne-shell script cgal_create_cmake_script is contained in the CGAL-4.0.1/scripts directory. It can be used to create CmakeLists.txt files for compiling Cgal applications. Executing cgal_create_cmake_script in an application directory creates a CMakeLists.txt containing rules for every *.cpp file there. Currently, that script only works for applications that only need the Cgal and CGALCore libraries.


Footnotes

 1  http://gcc.gnu.org/
 2  http://software.intel.com/en-us/intel-compilers/
 3  http://msdn.microsoft.com/en-us/vstudio/
 4  http://www.cs.nyu.edu/exact/
 15  CGAL-core++ is not part of Cgal, it is a custom version the CORE library distributed by Cgal for the user convenience and it has it's own license.
 16  The environment variable can be spelled either BOOST_ROOT or BOOSTROOT
 17  If both release and debug versions are available, this variable contains a list of the following form: 'optimized;<fullpath-to-release-lib>;debug;<fullpath-to-debug-lib>', where the 'optimized' and 'debug' tags should appear verbatim.